This section provides a few general conventions for GeoServer developers, about formatting code, testing, directory structures, refactoring, and logging.

Coding Conventions

GeoServer follows the Sun's coding standards. Developers need not all develop exactly to the standard, as we make use of Jalopy, a source code formatter. It lays out any valid Java source code according to configurable rules to meet a coding style without putting a formatting burden on individual developers. It is required to set up Jalopy, which is easily integrated with most IDE's (and available on the command line). The coding convention for GeoServer is contained in the 'documents' folder: jalopy.geoserver.xml. It will put on the correct header for you, in addition to formatting all the code. If there are parts of the code that you do not want formatted with Jalopy then you can insert //J++ and //J-- before and after the blocks of code that should not be jalopied.

One thing Jalopy does not do for you is get rid of .* imports. Code is much more clear if there are no mass imports, in the GeoServer code base we like every class used in the file to be explicitly named. This is easily done with most modern compilers, such as eclipse (organize imports). Please make use of it.

Also note that every method should have a javadoc comment. Please do not leave any undocumented, as some other developer will have to clean up your omissions, and that's a great way to make developers hate life. Most people do not like documentation, especially not when it is someone else's code. Each class should also have a good comment explaining what it does, along with @version and @author tags. For the version tag we recommend letting subversion control it, if creating a new class then just put

$Id: hacking.xml 2976 2004-10-13 23:25:25Z cholmes $

for the version, and it will be formatted when first committed.

One last convention is commit comments. When committing code the -m tag allows you to specify a message. Please make use of this with an informative message about the code you are committing. It helps out immensely, especially when other bugs may be introduced. Make a comment for every commit, and try to use complete, useful sentences.

Adding Functionality

For minor functionality the easiest thing to do is to just make a JIRA task, and then attach the new code there. If you do not have commit rights it will be reviewed and rolled in to the code base. If you do have commit rights then just ask someone else to review it, and you can commit it yourself.

For major functionality we have a bit of a process. This is to ensure that work is taken into the core in a timely manner.

1) Create a new wiki RnD page.

The first step is making a new proposal on the GEOS:RnD page. This should contain the functionality you would like to add, as well as some thoughts on how to implement, and perhaps the potential impact on the codebase. For many proposals this will bleed over into GeoTools, where one should also make an RnD page.

2) Email the list for feedback

Next email the geoserver-devel list about the page you created. Other developers can then take a look at what you are intending. There will likely be others who have thought about it before, and can help with design, and potentially even execution. Changes that will affect a lot of people may be asked to be on a branch.

3) Place tasks on JIRA

The project plan should be divided into tasks, and hopefully scheduled against a release, in the task tracker. If one does a nice job of sub-dividing the work it is easier for others to jump in and contribute.

4) Work, work, work!

Do the work, on a branch if requested. If on a branch update against head as often as possible, so as to minimize the pain when integrating.

5) Merge (if necessary) and release.

...and bask in the glory of your contribution to the world!

Testing

Tests in geoserver fall into a number of categories.

JUnit Tests

JUnit tests run against classes of the geoserver code base base in isolation. They are located in the test/ directory of the source tree. You can run all units tests by executing the unit-all ant task from the root of the source tree.

[geoserver]% ant unit-all

There are several targets to run groups of tests, such as 'unit-requests', and the 'unit' target allows you to pass in a package and class of a single test to run with the 'test.name' parameter.

We recommend running unit tests as frequently as possible, and before any commit.

For more information on writing junit tests explore junit.sourceforge.net.

Http Unit Tests

The second type of unit tests are known as Http Unit tests. They are JUnit tests which are run against a running instance of geoserver. An http unit test works by making a request to the server and examining the response. This form of testing is very similar to the cite tests described below. The http unit tests are located in the httptest/ directory of the source tree.

Running the http unit tests requires a number of steps.

1. Edit the httptest.properties file which contains the paramters needed to locate the running geoserver instance. The file is located in the root of the source tree and contains the following properties:

   protocol	Protcol used by the sevrver, default is 'http'
   server	IP address or DNS resolvable name of the server, default is 'localhost'
   port	Port used for communication with the server, default is '8080'
   context	Web Context under which geoserver is located, default is 'geoserver'

2. Start the geoserver instance.
3. Execute the unit-http ant task from the root of the source tree.

   [geoserver]% ant unit-http

Here is an example of a simple Http Unit test. For more complete documentation check out httpunit.sourceforge.net.

Cite Testing

CITE (Conformance and Interoperability Testing and Evaluation) tests are a set of tests published by the OGC for testing the compliance of WMS and WFS servers. They are very complete and very effective. GeoServer is required to pass all cite tests for any non-beta release.

The cite/ directory is especially useful for setting up the tests on PostGIS. The other DataStores will not work as well, not because we are not extremely confident in them, much more because CITE is extremely rigid about the data that must be used and implicitly imposes a number of requirements, for example the server must support more than 10 characters for attributes, which shapefiles do not support (at least not without implementing non open standard helper files). For open source tests, we highly recommend the WMS and WFS suites developed as part of the ACE-GIS project. They are available online. And if you are interested in the source files and running them yourselves, then email the list, as we have access to them, and indeed are looking to make them available for download on the GeoServer community site.

Here is a guide about how to set up a Cite test suite.

Hand Testing

Between the forms of testing mentioned above is testing GeoServer by hand, issuing a number of requests to ensure that nothing major was broken. To do this we highly recommend using the 'demo' section of the web administration tool. This allows you to easily issue 'post' requests, by just filling them into the form. And you can also put pre-configured requests that you use a lot in the 'demo' folder. See the section on the CITE folder for more information about flexible build configurations (also see 4 GeoServer Data Directory. We recommend making use of these for joint debugging, so that developers are assured of having exactly the same set up.

The best way to get acquainted with how to write tests is to look at the current tests, and model your tests after those. We also recommend trying Test Driven Development, that is, if you are going to write a new interface or method then you write the test first, and then the code to solve the exact problem. For more information on test driven development go here.

Bug Fixing

When you are fixing bugs, please follow these best-practices:

• All bug fixes, even very minor, should have a JIRA task associated with them, so that we can track what happened in each release, without having to go to the commit logs.
• Be verbose in your commit comments, explaining the changes made.
• Attach a link to the Jira task to the commit message of the files you are comitting for the bug,
  ie. "Fixed a logging error, see the bug report here: http://jira.codehaus.org/browse/GEOS-583"
• Try to commit all of the files related to a bug (or improvement) in one commit so they can be rolled back easier. Or at least in logical chunks.
• When you close the task in Jira, put the version numbers of the commits. Such as "r4382".
• If you're committing a patch, use the unix patch command (patch -p0 < file.patch) to ensure that it matches exactly. Give the person who submitted the patch credit on the commit comment.

Refactoring

Refactoring is the process of restructuring/renaming your code to ensure your design remains clean as your requirements and functionality change and grow with time.

Refactoring is best explored using the excellent book writen my Martin Fowler.

We are fans of refactoring in the GeoServer Project, we like to start with the minimal design and refactor when needed, instead of trying to anticipate everything in advance. If you've started a class that spirals out of control and could be better designed, then have a go at refactoring. Just be sure it passes all the tests.

Subversion Warning SVN wants to know what you are doing, please use the svn mv name1 name2 command when refactoring to let svn keep track of history information. This is especially important when using either of the tools below - although we can hope that more complete svn intergration is available for Eclipse shortly.

This is of utmost importance when refactoring, so no history is lost.

RefactorIt

To ease refactoring you can use RefactorIt which provides tools to:

• research, probe and understand existing source code,
• move, organise and transform existing code,
• and provide code metrics.

More details can be found from the online help.

RefactorIt is commercial, but provides free licences for Open Source projects like Geotools. See the RefactorIt web pages for details. It can be plugged into a variety of IDEs, including Netbeans.

Installation in to GEOTOOLS:Netbeans fairly strait forward through Tools -> RefactorIt -> Project Options, although setting up soucepath and classpath is a difficult if some of the geotools files don't compile. You will need to either remove the offending files, get them to compile or remove them from RefactorIt's sourcepath.

Eclipse Refactoring

Eclipse has many refactorings available, mostly through context menus.

Logging

Most GeoServer logging conventions are directly inherited from GeoTools

In general, most programmer level logging should be at FINE and less. INFO should be messages to users of things going on, and kept to a minimum. FINE is good for things that happen once per request, FINER for repeated actions.

Do not use any System.out calls

System.out calls are much harder to turn off. There should always be a logger available, and if there's not just add a standard one.